Mac Expert 1995 Winter/Mac Expert - Winter 95.iso/Les fichiers/Utilitaires divers/Images/Mac POV Utils 1.1 ƒ/POV-Utils Docs 1.1

Text File | 1993-03-23 | 13.2 KB | 306 lines | [TEXT/ttxt]

POV-Utilities for the Macintosh
===============================
3/23/93, version 1.1
Collected and ported to the Macintosh
by Eduard [esp] Schwan

Introduction
------------
The POV-Utilities are a rather diverse collection of programs that have
been designed to extend or ease the use of ray tracers.  This diversity
extends to the authors of the utilities as well, since many people have
created them.  Many of these utilities have been around for a while, but
mostly on the IBM PC platform only.

The intent of the author of a utility is usually to take care of an
immediate need, not to create a general purpose piece of source code.
Therefore, the utilities have been written in everything from IBM PC batch
files and Unix AWK scripts, to BASIC and C. Currently, only the C
utilities have been converted to the Macintosh, since they are the
easiest to port.  There are more C utilities that have not yet been
tackled, but that's just a challenge, I guess.

To give you an idea of the variety of these utilities, here's a
one-sentence synopsis of each utility currently in the Macintosh suite:

** Coil Generator - Bill Kirby
Generates intertwined coiled toruses of spheres.

 * Connect the Dots (CDTS) - Truman Brown
Takes an input text file of XYZ coordinates and writes a POV-Ray
output file that consists of spheres and connecting cylinders
between them.

 * Dat2POV - Drew Wells
Does a 95% automatic source conversion from POV-Ray 0.5 source to
POV-Ray 1.0 source syntax.

 * DXF2POV - Aaron A. Collins
Converts AutoCAD DXF (interchange) text files into POV-Ray
source files.

 * "Lissa" Lissajous Generator - Eduard [esp] Schwan
Generates a CTDS file of a lissajous-style 3-D woven mesh
curve of dots.

 * POV Suds Generator - Sam Hobbs & Dan Farmer
Generates a POV-Ray source file of "osculating spheres" of different
sizes and textures.

 * Raw2POV - Steve Anger
Converts a text file of raw triangle vertex coordinates into a POV-Ray
source file of either regular or smooth triangles.

 * Shell Generator - Dan Farmer
Generates a POV-Ray (or CTDS) source file of a snail-shell spiral
of spheres.

 * Sponge Generator - Stephen Coy
Generates a POV-Ray source file of a recursive cube lattice
of spheres.

 * Swoop - Douglas Otwell
Converts a "SWOOP" language input text file into a raw triangle text file.
This raw file can then be run through Raw2POV to create a POV-Ray source
file.  The SWOOP file can describe iterative translations and rotations of
2-D polygons, creating a 3-D extruded surface. This object is made up of
triangles on the POV-Ray side.

Requirements
------------
-Any Macintosh (Mac Plus to Quadra)
-System 6.0.4 or better (tested mostly under System 7)
-Color Monitor preferred but not required
-Some utilities may require 2 MB or more of memory, but most utilities
 will run in 1 MB.

Features
--------
-Easily pop between utilities using menus
-Uses (slightly) more intuitive dialog boxes for user parameters
-Supports multiple monitors (dialogs follow the status window)
-Status window text can be saved to a text file for logging purposes.

General Instructions
--------------------
POV-Utilities is a typical Macintosh application (whatever that means.)
Just double-click it, check out the nifty startup graphics, and choose the
utility of your choice from the "Utilities" menu.  Oh, you can peek at the
About box too!

Each utility behaves similarly, so here's a general step-by-step guide:

Choose the utility you want from the Utilities menu.

You are now presented with a dialog box of options to fill out.  Enter
the appropriate values, select the input or output file, and click the
"OK" button.  Note that some utilities REQUIRE that you pick an output
file.  The OK button will be dimmed until you do so.

The utility will run, displaying progress information as it goes.
Depending on the utility, it could take anywhere from seconds to
minutes to complete.  While it is running, the cursor changes to a
wristwatch, reminding you that the computer is busy pondering a way to
escape its current situation.  Some of the utilities display dots or
other progress information as they run.  When the utility does complete,
the cursor returns to an arrow.

If, for some reason, you wish to cancel the running utility before it
completes, you may hold down the command key and press the period key,
or choose "Stop" from the File menu.

WARNING: Unfortunately, cancelling the running utility will most likely
leave the utility in an unstable state, possibly with files left open. You
can run other utilities without a problem, but you will probably not be
able to run the stopped utility again without getting spurious file
errors.  It won't hurt anything, but you will find that you need to quit
the POV-Utilities application, and restart it.  After this, all will be
well again.  This is just an unfortunate side-effect of allowing the user
to exit the utility to exit at any time.

A time stamp is displayed in the status window, each time a utility
starts or stops.  This lets you know how long a utility takes to
do its thing.

When the utility is finished, you may pick "Save As" from the File
menu to save the Status window content as a text file.  This may
be useful for keeping track of which files you have processed, or
for timing different utilities, etc.

Specific Instructions
---------------------
The best information for each utility is currently provided by
each author of that utility.  Therefore, partially out of
consideration of the great talents of these authors, and partly
as a dodge so I don't have to try to consolidate and rewrite this
vast variety of documentation, I have included the original
documents for each utility, as-is.  This means that you will need
to read over those documents to better understand the specifics
of each utility.  You won't get it all in this one.  Also, I have
put the name and e-mail address (where known) for each author
in each utility's dialog box.

The Tutorials
-------------
I am also posting a TUTORIAL folder along with this package, which has
some documentation and example files, made specifcally to show you how to
use each of these utilities with POV-Ray.  These examples were created by
me, not by the utilities authors, and thus I bear full blame for any
mistakes or inaccuracies in these examples, not them.

Currently, the turorial package is not quite complete.  I have tutorials
for all the scene creation utilities, but not all the conversion
utilities. I welcome feedback on the package, and hope to finish it sooner
or later. I have posted it as a Macintosh archive, and also as an IBM PC
archive.

The Tutorial documentation and example files are FreeWare, and the author
reserves all rights to them.  They may not be distributed separately from
the Tutorial package.

Known Bugs
----------
POVSUDS - Telling it to create a ton of suds, and a too-small area to
create them in may result in the utility unsuccessfully hunting forever
for places to put suds.  You will need to cancel and try again with fewer
suds, a larger area, or smaller radii.

Cancelling a utility (cmd-period) often leaves that particular utility in
an unstable state.  It cannot be run again unless you quit the
POV-Utilities application and run it again.  Other utilities will be OK.

Although this is a "final" release, the ported utilities have only been
minimally tested on the Macintosh (by my standards, anyway.)  I am very
interested in hearing of any problems you have with this.  Please try to
give as much information about what hardware and software you are running
this on, what INITs/extensions you have, and what led up to the problem.
The more information I get, the more quickly I can find and (hopefully)
fix the problem. Currently, the utilities all seem to be working well,  I
know of no nasty crashes, even on Quadras.

The Future
----------
In this release of the Macintosh POV-Utilities, all the utilities are
grouped into one large monolithic Macintosh application.  This was
primarily done out of expedience for the Macintosh author, not because it
was necessarily the best thing for the user.  The next release will likely
see these as separate applications, each with a nice System 7 drag-n-drop
interface and life of its own.  This would also better handle the
non-synchronized release schedule of all the independent utilities.

With AppleEvent and maybe even AppleScript support, these utilities could
become quite powerful.  I also wish to port some other important utilities
that I haven't gotten to yet.  There's POVGen, FrGen, SPD, etc... We need
some image conversion utilities (Targa/GIF/PICT), and maybe the C
Beutifier that is used to help format the source code and scene files.  We
also need a POV 1.0 to 2.0 source converter.  I am also interested in
further automating the creation of animation files for POV-Ray (watch for
POV-Ray 2.0!)  Of course, if you find (or create) utilities that you would
like me to know about, please contact me!

Source Code
-----------
The latest source code for most of these utilities can be found on
either CompuServe or America Online, or by contacting the authors.
I do not have permission to redistribute their source code, and do not
want to stay on top of the constant updates.  Therefore, I have sent
my changes back to each author in the hopes that they will roll them
into their future releases.  That way, the re-integration of their
source back to the Mac will be much easier.

Some Source Code Notes
----------------------
The POV-Utilities are a collection of stand-alone programs
that each perform useful functions.  In the Macintosh
world, we have combined these into a single mongo
application. The idea behind the source code setup in this
project is to insure a MINIMUM set of changes to the
standard C programs, so that any updates to these source
files from the original authors will MINIMALLY impact our
Macintosh changes, and that the Macintosh changes to these
files minimally impacts the authors' works, and is still
portable across platforms.

How do you do that?
For example, there is a utility program called CTDS.  It
has a main program source file called CTDS.C.  I created
some code to prompt for the parameters for this utility,
and called the files CTDS.mac.c and CTDS.mac.h. CTDS.mac.h
also includes a #define that changes the main() function in
CTDS.C into a regular function call called CTDS_main(). We
can now link together many "main programs" and call them as
subroutines from our true Mac main program, contained in
the file POV-Utilities.c. The only change to CTDS.C is the
addition of the following lines of code, near the top of
the file:
    #if defined(applec) || defined(THINK_C)
    // if using Macintosh, include user interface stuff
    #include "CTDS.mac.h"
    #endif
Another important point is to make all your C functions
"static."  This insures that when independent utilities are
linked together, their identically named functions don't
collide at link time. The final proposal is to try to
allocate any large global data structures dynamically
(malloc) as opposed to declaring them as static global
variables.  This cuts down on global data space
requirements.

Please follow these guidelines when adding new utilities,
creating a standard stand-alone application with all the
usual parameter passing of K&R C, and a separate file that
contains the Mac-specific user-interface routines to
prompt the user for those same parameters.  This will allow
any new Mac utilities to flow easily back the other way,
to our other POV-Ray computer-kin.

Bottom Line
-----------
This software is a collection of FreeWare and Public Domain software,
ported to the Macintosh.  This Macintosh application is provided as
FreeWare.  The author reserves all rights to the Macintosh application.
It may be freely distributed, but not for profit.  Feel free to send
(Mac-related) bug reports, enhancement ideas, new utilities, etc. to
Eduard Schwan.

Additional References & Information
-----------------------------------
The POV-Ray raytracer is an ongoing FreeWare project being developed on
CompuServe.  The executable and the source code can be found there, on the
Graphics Development forum (GO GRAPHDEV.)  You can also find it on America
Online, on the PC Graphics (PGR:Company Support:POV Ray) forum.

Image Lab, Tim Wegner, Waite Group Press, 1992.  This book talks about
POV-Ray, and a couple of the utilities.

Credits
-------
The original authors really deserve 99% of the kudos for their ingenuity.

Jim Nitchals began porting and enhancing many of the POV-Utilities prior
to my mucking about with them.  He has also beta tested them, and insured
the source compiled under Think C.

I have incorporated many of Jim's enhancements into the utilities, and
have been sending the proposed updates back to the appropriate authors. I
also created the TUTORIAL materials, posted elsewhere nearby.

Of course, none of this could have happened if I had paid the proper
amount of attention to my wife and children.  Their infinite patience and
affection have pulled me through some otherwise meaningless late nights of
coding, testing and documenting. Therefore, all I ask is that if you find
these works useful, please let me (and my family!) know that my work has
benefitted you as well.  And of course, let the authors know that you are
enjoying their tools too!

Thank you,
Happy Raytracing!
[esp]

Author Contact
--------------
Eduard [esp] Schwan
CompuServe: 71513,2161
AppleLink: jl.mactech
Internet: [e-mail]